# Zombie Navigator

Free Software browser automation product

This is currently part of the DesktopD Project.

Good solutions to web automation have always been desired. In Mozilla world, SlimerJS (similar to PhantomJS) exists but it is strictly not Firefox (but a different XUL application) and that limit its possibilities. Selenium doesn't catch up with latest Firefox and it also requires a lot of codes outside Firefox.

This addon tries to improve this situation. It is a pure-Firefox web automation product that is Free Software. When Firefox works, this addon should also work. So it can, being very lightweight, automate most to all Firefox-related use cases. There are many many Firefox-based or Firefox-embedded products in the world. We can now use this addon to run testsuites on these products without modification. In theory we can, and if not, it's a bug. (Though this is Firefox 38+)

With the addon you can automate Firefox (or derivatives) with a single script file you like. We call such a script a "Zombie script" and Zombie scripts use the "Zombie API" to do their jobs. The Zombie API is documented inside the addon but this is how it looks like:



    'use strict';
  
    const {delay, run} = require('zombie/async');
    const {console} = require('zombie/zombie');
    run(function* () {
      const {openWindow, openPrivateWindow} = require('zombie/webbrowser');
      try {
        let window1 = yield openWindow('about:');
        console.log(window1.uri);
        yield delay(5); // sleep for 5 seconds
        
        let promise = window1.runScript(uri => {
          location.href = uri;
          return 42;
        }, 'about:buildconfig');
        
        yield window1.waitForReload();
        console.log((yield promise), window1.uri);
        
        yield delay(10.5); // sleep for 10.5 seconds
        yield window1.close();
        console.log('closed');
      } catch (e) {
        console.error('Error:', e);
      }
    });



Command line (GNU/Linux):

`$ ZOMBIE_NAVIGATOR_SCRIPT_PATH=<path_to_script> firefox`

Command line (Apple OS/X):

`$ ZOMBIE_NAVIGATOR_SCRIPT_PATH=<path_to_script> /Application/Firefox.app/Contents/MacOS/firefox`

For pseudo-headlessness, Xvfb is supported. Use like this:

`$ ZOMBIE_NAVIGATOR_SCRIPT_PATH=<path_to_script> xvfb-run firefox`

A script can now most of times shut down Firefox if the user (if any) does not open any tabs. This feature is getting improved, but is incomplete. So please expect windows not closed properly in some cases.

Though this addon is simple, it is similar to SlimerJS. But this is a Firefox addon, like Greasemonkey, and not a standalone application. So it can easily be used to run automated tests with existing Firefox profiles (with your favorite addons installed). That makes it more useful inside an organization.

This addon is designed to change as little of Firefox as possible while it tries to make clear what the script is doing.

This addon is not a server-side application, but for maximum software freedom in case embedded in a SaaS product, we license the addon under the GNU AGPL.


## About

A simple Firefox automation addon


- `src/`        The addon source code
- `branding/`   Branding source code (artworks)
- `jsdoc/`   JSDoc-based API documentation source code (experimental)
- `run.sh`      Run the addon off the source tree (requires non-release non-beta Firefox due to signing requirement)
- `LICENSE`     The GNU Affero General Public License, version 3


Firefox (or equivalent) 38+ is required.


## **Build** requirements

- **NodeJS** and **NPM**
- Built using `jpm` (install with `$ make npm`)
- `JSDoc` for API documentation (install with `$ make npm`)
- *(Optional)* AdvanceCOMP (`advzip` utility) for a smaller file size (`$ apt-get install advancecomp` on debian-based systems)
- *(Optional)* Perl 5 (used for CSS minification)
- Build scripts only support Unix-like systems (Note that the shell scripts here use a POSIX `/bin/sh`, which is **not** necessarily GNU bash.)


## Building

- Prepare the up-to-date dependencies: `$ make npm` (note: huge dependencies)
- (Optional) Fetch and build `zopflipng` from Google: `$ make zopflipng` (please run if you don't have one installed)
- Build the addon: `$ make`
- (Optional) Rebuild the documentation with JSDoc: `$ make docs`
- (Optional) Create a source tarball: `$ make archive`
- (Optional) Rebuild the icons: `$ make icon`


## TODO

- Make sure the API is always reliable
- Run script from the `about:addon` page (`simple-script` module in the SDK)
- "Stop all" button in the `about:addon` page??
- Per-script user controls??
- Confirm that the addon should work properly in "partial restart" cases -> does nothing?
- Fade out JSDoc
- *Reset* preferences on uninstall (so that the next installation will be "fresh")?
- Use NodeJS for build scripts? (but remember we *hate* `npm` and `semver.org`)


## Branding

We named this program "Zombie Navigator" because it effectively turns
Firefox into an automated "zombie" web browser. "Zombie scripts", which
run inside a secure sandbox navigate Firefox!

The icon says "Web Browser" in Arabic. Just that. Maybe too simple. But we
do not invest much in visual design.

Firefox is a registered trademark of the Mozilla Foundation. The term
"Firefox" in this product, however, may also mean rebranded products
derived from the official Firefox.


## Versioning

- https://github.com/mojombo/semver/issues/145
- We use `~` for prereleases (compatible with AMO)


## License

Copyright © 2015  Zombie Navigator Developers

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.


The GNU Affero General Public License (GNU AGPL for short) is included under
the file name 'LICENSE'

